…ation

Extracts ParameterErrorCode and ParameterResult into a dedicated header
under core/configuration/. The structured-error contract becomes
available to the neutral build layer; the ConfigurationManager header
forwards to the new location.

Extracts FaultResult, the JSON-bag outcome shared by seven of the eight
fault-manager methods, into a dedicated header under core/faults/. The
existing FaultWithEnvResult still exposes raw message types and stays
inside fault_manager.hpp until the transport extraction moves the
message-to-JSON conversion to the adapter layer.

…sports

Defines seven abstract ports - TopicTransport, ServiceTransport,
ActionTransport, ParameterTransport, FaultServiceTransport, LogSource,
TopicSubscriptionTransport - that the manager refactors will route through.
Each port carries the same operations the corresponding manager performs
today, expressed in pure C++ types (already-neutral result structs from
core/operations, core/configuration, core/faults). The smoke test extends
to assert each interface is abstract and reachable from the gateway_core
build layer with no ament dependency on the link line. Adapter
implementations land under src/ros2/transports/ in subsequent phases.

Two name choices avoid collisions with structs that currently live in the
ROS-coupled headers:

* TopicTransport::sample returns TopicSample rather than TopicSampleResult,
  because core/data/data_types.hpp already defines a same-named struct
  with a different shape (per-topic batch errors, endpoint QoS) for the
  topic-data-provider plugin surface.
* FaultServiceTransport::get_fault_with_env returns FaultWithEnvJsonResult
  rather than FaultWithEnvResult, because the legacy
  ros2_medkit_msgs-typed FaultWithEnvResult still lives next to the
  FaultManager facade. The two will be reconciled when the FaultManager
  migration lands.

TopicSubscriptionHandle is a polymorphic RAII base (virtual destructor
only) rather than a fully abstract port, so the smoke assertion uses
sizeof > 0 instead of std::is_abstract_v.

…sports

OperationManager retains all goal-tracking, UUID generation, validation,
and component-namespace resolution logic in pure C++. The rclcpp side -
GenericServiceClient cache, action-internal-service clients, the
GoalStatusArray subscription cache - moves into two new adapters,
Ros2ServiceTransport and Ros2ActionTransport, under src/ros2/transports/.

The manager registers a per-goal status callback at subscribe time so
the action transport pushes goal-status updates back into the manager's
tracking map on its own thread. Goal-status array decoding moves into
the transport; the manager only consumes the typed (path, goal_id,
status) tuples. The handler-facing public API (call_service,
call_component_service, send_action_goal, send_component_action_goal,
cancel_action_goal, get_action_result, list_tracked_goals,
update_goal_status, update_goal_feedback, cleanup_old_goals,
subscribe_to_action_status, unsubscribe_from_action_status, the four
static is_*-type helpers, the UUID helpers) is preserved.

The component-name resolver dependency moves behind a new
ServiceActionResolver port that DiscoveryManager now implements; this
keeps the manager translation unit out of discovery_manager.hpp's
rclcpp transitive include chain. Mock-transport tests link only against
gateway_core + GTest, exercising 13 routing / lifecycle scenarios.

ConfigurationManager loses its rclcpp::SyncParametersClient cache, the
rclcpp::Parameter defaults cache, the negative-cache for unreachable
nodes, and the spin_mutex serialising parameter-client spins. All of
these move into the new Ros2ParameterTransport adapter under
src/ros2/transports/. The adapter also owns the JSON <-> rclcpp::
ParameterValue conversion helpers and the gateway-own-FQN check that
previously lived as private members of the manager.

Manager retains: per-entity reset orchestration (reset_parameter and
reset_all_parameters compose set_parameter with transport-supplied
defaults via the new get_default and list_defaults methods on
ParameterTransport), the self-node short circuit (delegated to the
transport's is_self_node), and the shutdown ordering contract
(idempotent manager.shutdown() fans out to transport.shutdown() before
rclcpp::shutdown()).

The handler-facing public API (list_parameters, get_parameter,
set_parameter, reset_parameter, reset_all_parameters, shutdown) is
preserved verbatim; the legacy include path
ros2_medkit_gateway/configuration_manager.hpp is preserved as a
forwarding shim. Parameter-service tuning parameters
(parameter_service_timeout_sec, parameter_service_negative_cache_sec)
are declared at gateway_node wiring time and passed to the transport
constructor.

ParameterTransport gains two new pure-virtual methods (get_default,
list_defaults) that surface the cached defaults as neutral JSON for
manager-level reset orchestration. The gateway_core link-time smoke
test now also pins ConfigurationManager. Mock-transport tests link
exclusively against gateway_core + GTest, with no rclcpp on the link
line, covering CRUD delegation, self-node short-circuit, reset via
cached defaults, partial-failure aggregation in reset_all_parameters,
and shutdown idempotency.

FaultManager loses its seven rclcpp::Client members and their seven
per-client mutexes; all move into the new Ros2FaultServiceTransport
adapter under src/ros2/transports/. The adapter performs the
ros2_medkit_msgs to JSON conversion internally and returns the neutral
FaultResult / FaultWithEnvJsonResult structures, so the manager body now
lives in the ROS-free build layer (gateway_core).

The handler-facing public API (report_fault, list_faults, get_fault,
get_fault_with_env, clear_fault, get_snapshots, get_rosbag,
list_rosbags, is_available, wait_for_services) is preserved verbatim.
The single behaviour change is that get_fault_with_env now returns
the response body as JSON: data carries { "fault": {...},
"environment_data": {...} } already converted by the transport. The
single handler call site (build_sovd_fault_response) is updated to
consume the JSON, post-processing rosbag snapshots to add the per-
request bulk_data_uri and freeze_frame snapshots to extract the
primary value.

The previously static FaultManager::fault_to_json helper is removed.
Two external call sites (SSEFaultHandler, TriggerFaultSubscriber)
subscribe directly to the FaultEvent topic and convert the message
themselves; they now use the small ros2/conversions/fault_msg_conversions
module that lives at the ROS-coupled boundary alongside the transport.

The legacy include path ros2_medkit_gateway/fault_manager.hpp is
preserved as a forwarding shim. New mock-transport tests link only
against gateway_core + GTest, proving the manager logic compiles
without rclcpp on the link line.

LogManager keeps its ring-buffer storage, per-entity config map, monotonic
id counter, plugin observer pattern, and the manages_ingestion
short-circuit - all pure C++. The /rosout subscription and the
rcl_interfaces::msg::Log to LogEntry conversion move into the new
Ros2LogSource adapter under src/ros2/transports/. The adapter emits
LogEntry through a callback the manager registers at start() time;
when the primary LogProvider declares full ingestion, the manager never
calls start() (matching today's behaviour of not creating the
subscription at all in that mode).

To let the manager body live in gateway_core alongside the other
managers, the PluginManager pointer is replaced with a thin
LogProviderRegistry port (primary_log_provider + log_observers).
PluginManager implements the port inline, so production wiring is
unchanged. The handler-facing public API (get_logs, get_config,
update_config, add_log_entry, set_notifier,
set_node_to_entity_resolver, the static helpers,
inject_entry_for_testing) is preserved verbatim.

Mock-source tests link only against gateway_core + GTest, proving the
manager logic compiles without rclcpp on the link line. The legacy
include path ros2_medkit_gateway/log_manager.hpp is preserved as a
forwarding shim.

…sport

TriggerManager keeps all its condition-evaluation, retry-unresolved,
sweep-orphaned, persistence, dispatch-index, and entity-cache logic in
pure C++. The pointer to TriggerTopicSubscriber is replaced with a
shared TopicSubscriptionTransport interface; the new
Ros2TopicSubscriptionTransport adapter wraps the existing
TriggerTopicSubscriber, preserving its subscription-destructor pattern.
Per-trigger subscription handles live in the manager's tracking map -
destruction unsubscribes - so trigger lifetime fully drives subscription
lifetime.

The trigger manager source moves to src/core/managers/ so it is picked
up by gateway_core's GLOB. TriggerTopicSubscriber moves to
include/ros2_medkit_gateway/ros2/ and src/ros2/, and a forwarding
shim at the old header path keeps existing includes working.

TriggerTopicSubscriber itself becomes a generic per-handle subscription
executor: subscribe(topic, type, handle_key, callback) creates one
GenericSubscription per key, unsubscribe(handle_key) tears it down,
and pending/retry semantics are preserved with the same 60s timeout.

The handler-facing public API (create / get / list / update / remove,
wait_for_event, consume_pending_event, set_on_removed,
set_entity_children_fn, set_entity_exists_fn, set_resolve_topic_fn,
retry_unresolved_triggers, sweep_orphaned_triggers,
load_persistent_triggers) is preserved verbatim.

Mock-transport tests link only against gateway_core + GTest, proving
the manager body compiles without rclcpp on the link line.

RuntimeDiscoveryStrategy is replaced by Ros2RuntimeIntrospection, which
implements the existing IntrospectionProvider interface used by the
merge pipeline for plugin-driven entity discovery. Built-in ROS graph
queries are now treated identically to plugin-provided introspection -
one chain, one merge policy.

HybridDiscoveryStrategy is removed; the equivalent runtime + manifest
+ plugin merge is the default MergePipeline configuration. The
discovery_mode parameter (runtime_only / manifest_only / hybrid) now
controls which layers the merge pipeline activates rather than which
strategy class to instantiate.

The class is the rosidl_typesupport_cpp + rosidl_typesupport_introspection_cpp
bridge built on top of JsonSerializer; it semantically belongs alongside the
rest of the rosidl glue rather than in the gateway. Gateway packages now
depend on the serialization library for type schemas instead of duplicating
the introspection backend.

- Move type_introspection.{hpp,cpp} to ros2_medkit_serialization (preserves
  Apache 2.0 header verbatim).
- Migrate the namespace from ros2_medkit_gateway to ros2_medkit_serialization;
  qualify all consumer call sites (gateway managers, transports, providers,
  handlers, discovery, tests).
- Update forward declarations in topic_transport.hpp,
  data_access_manager.hpp, discovery_manager.hpp.
- Move the TypeIntrospection unit suite from
  src/ros2_medkit_gateway/test/test_data_access_manager.cpp to
  src/ros2_medkit_serialization/test/test_type_introspection.cpp; register
  the new test target.
- Drop src/type_introspection.cpp from the gateway gateway_ros2 source list.

The rosidl_typesupport_cpp / rosidl_typesupport_introspection_cpp deps remain
in the gateway because the GenericClient compat shim still uses them.

Replace the cyclic wall-timer loop that called refresh_cache() every
refresh_interval_ms with an event-driven design:

- A 100 ms wall timer polls rclcpp::Node::get_graph_event()->check_and_clear()
  and runs refresh_cache() only when the ROS 2 graph actually changed (node
  up/down, topic/service/action add or remove). On a stable graph the
  callback is a single atomic check.
- A second wall timer at refresh_interval_ms acts as a safety backstop,
  forcing an unconditional refresh so liveness is preserved if a graph
  event is ever missed.

Semantics of the existing refresh_interval_ms parameter shift from
"primary refresh interval" to "safety-backstop interval", and the default
moves from 10 s (gateway_params.yaml) / 2 s (gateway.launch.py) to 30 s.
The validation range stays 100-60000 ms; existing test overrides at
1000 ms continue to work, just as a tighter backstop.

Test impact:

- New integration test verifies that a node spawned mid-run appears in
  /apps within 5 s while the gateway runs with a 30 s backstop, proving
  the graph-event poll path is what drives the refresh.
- test_operation_handlers seeds the entity cache directly and used to
  rely on refresh_cache() never firing during the 1 s settle period.
  Graph events from the test executor now do trigger refreshes; seed
  after the settle so the test's manually-injected component wins.

Design intent on idle CPU: the previous timer woke and ran the full
refresh_cache() pipeline every refresh_interval_ms regardless of whether
the graph had changed. With this change an idle gateway runs only the
100 ms graph-event check (a single atomic load) plus the 30 s backstop.

Documentation updated: README.md parameter tables, gateway_params.yaml
comments, design/aggregation.rst.

Persistent triggers loaded at startup were being removed before DDS
discovery had populated the entity cache. The graph-event refresh path
fires on every node up/down event, including the cold-start window where
the cache reflects only a partial view of the ROS 2 graph. Running the
orphan sweep on every graph event treated restored triggers as orphans
because their target entities had not yet been seen by this gateway,
removing them from both memory and the persistent SQLite store.

Move the sweep call to the backstop timer only. The backstop runs at the
configured refresh cadence (default 30 s, 1 s in tests), giving DDS time
to converge before any orphan check. The graph-event path keeps doing
the cheap cache refresh, so spawn-detection latency is unchanged.

Each test in the suite connects to a non-existent OPC UA host and waits
about 3.8 s for the DNS / TCP failure path. With 13 tests the wallclock
run requires roughly 90 s. The ament_add_gtest default timeout of 60 s
truncated the run mid-suite, which CTest then surfaced as a
"missing_result" error under heavy parallelism (visible in concurrent
colcon test invocations on multi-core hosts).

Set TIMEOUT 240 to give a comfortable margin without hiding genuine
hangs.

The neutral-managers refactor moved DataAccessManager, OperationManager,
ConfigurationManager, FaultManager, LogManager, and TriggerManager into
``gateway_core`` and gave each one a Transport interface for ROS
interaction. Update the layered-library note to reflect that placement
and the new neutral interfaces.

TriggerTopicSubscriber became a generic per-handle subscription executor
wrapped by Ros2TopicSubscriptionTransport. Update its class summary,
component list, and the TriggerManager arrow on the class diagram so
they describe the new per-trigger handle ownership rather than the old
reference-counted shared-subscription model.

Apply clang-tidy fixes across the files this branch already modifies so
the incremental clang-tidy job (which scans every file changed in a PR)
stays clean.

- ``fault_handlers.cpp``: replace temp-allocating ``operator+`` chain in
  ``bulk_data_uri`` construction with explicit ``operator+=`` /
  ``std::move`` (performance-inefficient-string-concatenation).
- ``test_configuration_manager.cpp``: pre-allocate ``threads.reserve(...)``
  before ``emplace_back`` loops (performance-inefficient-vector-operation).
- ``test_configuration_manager_routing.cpp``,
  ``test_data_access_manager_routing.cpp``,
  ``test_operation_manager_routing.cpp``,
  ``test_operation_handlers.cpp``: name unused parameters in mock and
  override signatures (readability-named-parameter,
  misc-unused-parameters).
- ``test_fault_handlers.cpp``: switch single-character
  ``std::string::find("X")`` calls to ``find('X')``
  (performance-faster-string-find).
- ``test_operation_handlers.cpp``: replace ``std::bind(...)`` with
  forwarding lambdas (modernize-avoid-bind), and pass shared_ptr
  arguments by const-reference instead of by value
  (performance-unnecessary-value-param).
- ``test_trigger_manager_routing.cpp``: use ``empty()`` instead of
  ``size()`` in a boolean context (readability-container-size-empty).

After these changes ``clang-tidy -p build`` is clean on every cpp this
branch touches.

Follow-up to the earlier clang-tidy fixup. After clang-format wrapped
the goal-callback lambda onto its own line, clang-tidy re-evaluated
the parameter list and re-flagged ``goal`` as a copied
``std::shared_ptr`` only used as a const reference. Switch the
parameter to ``const ...&`` to match the rest of the action lambdas
in the file.

…hook

clang-tidy prints a 'X warnings generated. Suppressed Y' summary plus
source snippets on stderr even when every diagnostic is filtered out.
Streaming that for every clean file across a 100-file pre-push run fills
pre-commit's output buffer; the framework then fails with
BlockingIOError on sys.stdout.buffer.write and the push aborts before
git ever opens the connection.

Capture clang-tidy stdout+stderr per file and only emit it on non-zero
exit. Add --quiet to drop the progress lines that clang-tidy keeps even
when there are no diagnostics.

Effect: clean files produce zero output, so the framework never has a
multi-megabyte buffer to flush; only files with real findings produce
output, exactly as before.

…ndant c_str

Two pre-existing clang-tidy findings on the test fixture surface in the
pre-push hook now that the gateway PR brings the affected file into
scope:

- LocalHttpServer owns a std::thread and a raw httplib::Server pointer
  and declares a non-default destructor, so the project's
  cppcoreguidelines-special-member-functions check (with
  AllowSoleDefaultDtor) demands all five special members. Mark copy/move
  as = delete since the wrapped server cannot be safely duplicated.
- The httplib::Server::Get overload accepts a std::string by const
  reference, so the .c_str() conversion is redundant
  (readability-redundant-string-cstr).

…dentation

docutils 0.21 reads the second line of a wrapped sub-bullet as a new
indentation block (build-docs CI fails with -W under sphinx 8). Collapse
the wrap to a single line so the bullet text stays in the parent list.

Affects only line 466 of the design index; no semantic content change.

…stripped libcpp-httplib TSan races

Two CI failures uncovered after the rebase to the graph-event-driven
discovery refresh:

ASan failure on OperationHandlersFixtureTest.ListExecutionsReturnsTrackedActionGoal:
  Sending an action goal subscribes to the action's feedback/result
  topics, which the gateway's graph-event refresh observes and uses to
  rewrite the entity cache from its (empty) own discovery view, wiping
  the manually seeded engine component. Under ASan the refresh has more
  wall-clock to land between create_action_execution() returning and the
  subsequent handle_list_executions() call. Re-seed the cache from the
  helper after handle_create_execution so any subsequent handler call
  still sees the engine entity.

TSan races in libcpp-httplib.so triggered by daisy-chain aggregation:
  The reported races live in cpp-httplib's own listen / accept / response
  paths between two server threads spawned from RESTServer::start.
  An existing race:httplib::* suppression covers symbolised frames; the
  system-packaged .so however is shipped stripped, so the TSan stack ends
  in <null> frames inside libcpp-httplib.so.0.14 and the symbolic
  suppression no longer matches. Add a called_from_lib: rule for both the
  versioned and unversioned soname so the stripped frames are silenced
  the same way upstream-symbolised builds were.

Sanitizer-tsan was intermittently failing on test_daisy_chain_aggregation
because gateway_node-2 (peer_b) needed more than 15s to exit after SIGINT.
The hang sat between TriggerTopicSubscriber::shutdown completion and the
end of GatewayNode::~GatewayNode - i.e. somewhere in REST server stop or
member-destruction order. ASan-only runs squeezed in under the 15s grace;
TSan (heavier instrumentation) blew past it and the launch system
escalated to SIGKILL with exit -9.

Root cause: AggregationManager has no shutdown path. When SIGINT arrived
mid-forward, peer_b had REST worker threads blocked inside
PeerClient::forward_request's local httplib::Client::Get/Post call to
peer_c. The local Client cannot be stopped externally, and the per-call
read timeout (default 5000ms, ~25-50s effective under TSan) gates worker
exit. cpp-httplib Server::stop unblocks the accept loop but cannot
interrupt blocked client I/O on the worker side.

Fix: track every active outbound httplib::Client per PeerClient and add
shutdown() that calls stop() on each. PeerClient::ScopedClient RAII
helper registers/unregisters with the active set and is used by
forward_request, forward_and_get_json, and fetch_entities (replacing
the previous local Client). AggregationManager::shutdown() forwards to
every static + discovered peer. GatewayNode::~GatewayNode invokes
aggregation_mgr_->shutdown() right after stopping mDNS and BEFORE
stop_rest_server(), so REST workers mid-forward unwind on Error::Canceled
instead of waiting out the full read timeout.

Subsequent forwards after shutdown short-circuit with 503/error rather
than dialling the peer.

The first cut of PeerClient::shutdown() also called client_->stop() on
the lazily-created health-check client to be thorough. That added a TSan
report ('unlock of an unlocked mutex (or by a wrong thread)') and a
SIGABRT on Rolling: the health-check client is exclusively used inside
check_health() which holds client_mutex_ around the entire Get() call;
calling stop() on it from the shutdown thread races with cpp-httplib's
own socket_mutex_ while check_health still owns the socket internals.
On glibc + libstdc++ on Noble the mutex misuse aborts the process
(test_beacon_param::test_exit_codes saw exit code -6); under TSan the
warning is emitted and the test fails with exit code 66.

The health-check client is short-lived (single GET, bounded read
timeout), so leaving it alone during shutdown only delays exit by at
most one health-check duration. The multi-second shutdown hang we set
out to fix came from in-flight forward_request / fetch_entities calls,
which use ScopedClient and ARE in the to_stop snapshot.

…wn interrupt

After the previous round of shutdown work, test_leaf_collision_aggregation
still escalated to SIGKILL under TSan: in-flight forward_request calls
unblocked promptly, but the periodic check_health() call inside
PeerClient was still blocked in client_->Get() against the unhealthy
peer. That call holds client_mutex_ for the full read timeout (~5s
nominal, ~25-50s under TSan), and the cpp-httplib Client cannot be
interrupted from another thread unless someone calls Client::stop() on
it.

Register the lazily-created shared client_ with the active-client set
on first creation. shutdown() then iterates the set as before and calls
stop() on every registered client, which interrupts the in-flight
health-check Get() the same way it interrupts forward_request and
fetch_entities. The client lives for the rest of the PeerClient's
lifetime so we never unregister it; declaration order guarantees
active_clients_ is destroyed before client_ so no dangling pointer ever
sits in the active set.

Calling httplib::Client::stop() from PeerClient::shutdown() to interrupt
an in-flight Get/Post on a sibling thread is the upstream-documented way
to cancel a blocking client I/O call. The cpp-httplib internal mutex
sequencing in that path tickles TSan with an 'unlock of an unlocked
mutex (or by a wrong thread)' on every aggregation shutdown, but the
supported API contract is honoured and ASan / Rolling do not abort.

TSan attributes the report to the caller (peer_client.cpp:780 in
PeerClient::shutdown), so suppress by that symbol rather than by
called_from_lib - the existing 'called_from_lib:libcpp-httplib.so.0.14'
suppression covers race: reports but not mutex: reports against a stack
whose top frame is our own translation unit.

Health-check Get() against an unresponsive peer blocks for the
configured forward timeout (5s nominal). Under TSan that becomes
~25s effective and exceeds the launch_test 15s SIGINT-to-SIGKILL
grace, producing exit -9. We cannot use httplib::Client::stop() to
interrupt the call - cpp-httplib's stop() unlocks an internal mutex
from a thread that did not lock it, and glibc + pthread debug
(Ubuntu Noble) treats that as a fatal SIGABRT.

Instead, hardcode the health-check timeouts at 1s (or the configured
forward timeout, whichever is smaller). Health checks are
ping-shaped by design; an unresponsive peer is 'unhealthy' whether
we wait 1s or 5s. Capping the health timeout bounds shutdown delay
to ~5s under TSan, well inside the grace window, without affecting
forward semantics (forward_request and fetch_entities still use the
full configured timeout via ScopedClient, which IS interruptible
through the active-client registry).